客户端函数
这些主题描述了 GBase 8s ODBC Driver客户端函数。使用这些函数访问和操纵智能大对象以及行和集合。
仅当您的数据库服务器是 GBase 8s 时，这些函数才适用。
调用客户端函数
本节描述了客户端函数的语法，它们的输入/输出参数，返回值和 SQL_BIGINT。
SQL 语法
这是客户端函数的 SQL 语法。
{? = call _client_function_(?, ?,...)}
仅当第一个参数是输出参数时才使用首个参数标记符（“?”）。
以下代码示例当第一个参数是输出参数时，调用客户端函数的语法：
{? = call ifx_lo_open(?, ?, ?)}
下代码示例当第一个参数不是输出参数时，调用客户端函数的语法：
{call ifx_lo_create(?, ?, ?, ?)}
函数语法
数据库服务器和应用程序都可以部分实现客户端函数。
可以使用 SQLPrepare() 和 SQLExecute() 或者使用 SQLExecDirect() 执行客户端函数。在调用 SQLExecute() 或 SQLExecDirect() 之前，需要调用 SQLBindParameter() 或 SQLBindCol() 绑定每个参数。
使用 SQLPrepare() 和 SQLExecute() 执行客户端函数
可以使用 SQLPrepare() 和 SQLExecute() 执行客户端函数。
要使用 SQLPrepare() 和 SQLExecute() 执行客户端函数：
- 为客户端函数准备 SQL 语句。
- 绑定参数。
- 执行 SQL 语句。
下列代码示例说明了使用 ifx_lo_open()的这些步骤：
rc = SQLPrepare(hstmt, "{? = call ifx_lo_open(?, ?, ?)}", SQL_NTS);
rc = SQLBindParameter(...);
rc = SQLExecute(hstmt);
使用 SQLExecDirect() 执行客户端函数
可以使用 SQLExecDirect() 函数执行客户端函数。
要使用 SQLExecDirect() 执行客户端函数：
- 绑定参数。
- 执行 SQL 语句。
以下示例代码说明了使用 ifx_lo_open()的这些步骤：
rc = SQLBindParameter(...);
rc = SQLExecDirect(hstmt, "{? = call ifx_lo_open(?, ?, ?)}", SQL_NTS);
输入和输出参数
大多数客户端函数的输入和输出参数是客户端应用程序的输出参数。
但是，接受输入/输出参数的客户端函数会在内部初始化这些参数，然后将其发送数据库服务器，并请求执行客户端函数。因此，您需要将这些参数作为输入/输出参数传递给驱动程序。
SQL_BIGINT 数据类型
GBase 8s 支持 INT8 GBase 8s SQL 数据类型。
缺省情况下，驱动程序将 INT8 映射到 SQL_BIGINT GBase 8s ODBC Driver SQL 数据类型，SQL_C_CHAR 缺省映射为 GBase 8s ODBC Driver C 数据类型。但是，客户端函数不能访问所有的数据类型转换函数。因此，当使用 SQL_BIGINT 类型的值时，您必须使用除 SQL_C_CHAR 以外的数据类型。
例如，在调用 ifxlo_specset_estbytes() 之前，必须为 _estbytes 输入参数绑定一个变量。因为 estbytes 是 SQLBIGINT，通常会将 _estbytes 绑定到 SQL_C_CHAR。但是，对客户端函数，SQL_C_CHAR 不适用于 SQLBIGINT 。以下代码说明如何将 _estbytes 绑定到 SQL_C_LONG 而不是针对 ifx_lo_specset_estbytes() 的 SQL_C_CHAR：
rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_LONG,SQL_BIGINT, (UDWORD)0, 0, &estbytes, sizeof(estbytes), NULL);
rc = SQLExecDirect(hstmt, "{call ifx_lo_specset_estbytes(?, ?)}", SQL_NTS);
返回码
客户端函数不提供返回码。
有关成功或失败信息，请参阅用于调用客户端函数（SQLExecDirect() 或 SQLExecute()）的 GBase 8s ODBC Driver 函数的返回码。
智能大对象函数
本节描述了驱动程序为智能大对象提供的每个客户端函数。
ifx_lo_alter() 函数
ifx_lo_alter() 函数更改智能大对象的存储特性。
语法
ifxlo_alter(_loptr, lospec)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| loptr | SQL_INFX_UDT_FIXED | 输入 | 智能大对象指针结构 |
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
用法
ifx_lo_alter() 函数执行以下步骤来更改智能大对象的存储特性：
-
获取智能大对象的互斥锁。
-
利用 lospec 智能大对象中的特性来更新智能大对象的存储特性。ifx_lo_alter() 函数允许您更改以下存储特征：
-
日志记录特性
-
最后访问时间特性
-
扩展大小
-
-
解锁智能大对象。
作为调用此函数的另一种方法，如果您只想要更改其中的一个特性，则可以调用以下函数之一：
-
ifx_lo_specset_flags()
-
ifx_lo_specset_extsz()
ifx_lo_close() 函数
ifx_lo_close() 函数关闭智能大对象。
语法
ifxlo_close(_lofd)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
用法
ifx_lo_close() 函数关闭智能大对象。在此函数的操作期间，数据库服务器尝试解锁智能大对象。如果隔离方式是可重复读或者锁是互斥锁，则数据库服务器不会释放此锁，除非事务结束。
如果您不在 BEGIN WORK 事务块中修改智能大对象，则每次更改是一个单独的事务。
ifx_lo_col_info() 函数
ifx_lo_col_info() 函数更改具有列级存储特性的智能大对象规范结构。
语法
ifxlo_col_info(_colname, lospec)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| colname | SQL_CHAR | 输入 | 指向包含数据库列名称的缓冲区 该值必须具有下列格式： database@server_name:table.column 如果列在 ANSI 兼容的数据库中，则可以包含所有者名称。在这种情况下，使用以下格式： database@server_name:owner.table.column |
| lospec | SQL_INFX_UDT_FIXED | I/O | 智能大对象规范结构 |
用法
ifx_lo_col_info() 函数将智能大对象规范结构的字段设置为 colname 数据库列的存储特征。如果指定的列没有定义列级别存储特征，则数据库服务器将使用继承的存储特征。
在调用此函数之前，必须调用 ifx_lo_def_create_spec()。
ifx_lo_create() 函数
ifx_lo_create() 函数创建并打开新的智能大对象。
语法
ifx_lo_create(lospec, flags, loptr, lofd)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 包含新智能大对象的存储结构的智能大对象规范结构 |
| flags | SQL_INTEGER | 输入 | 打开智能大对象的方式。 |
| loptr | SQL_INFX_UDT_FIXED | I/O | 智能大对象指针结构 |
| lofd | SQL_INTEGER | 输出 | 智能大对象文件描述符。该文件描述符仅在当前数据库连接中有效。 |
用法
ifx_lo_create() 函数执行以下步骤创建并打开智能大对象：
-
创建智能大对象指针结构。
-
分配指针到此结构，在 loptr 中返回此指针。
-
从 lospec 指示的智能大对象规范结构中为智能大对象分配存储特征。
如果 lospec 为空，则 ifx_lo_create() 使用系统指定的存储特征。如果智能大对象规范结构存在，但是不包含存储特征，则 ifx_lo_create() 使用继承层次结构中的存储特征。
-
以 flags 指定的访问模式中打开智能大对象。
-
关联智能大对象和当前连接。
关闭连接时，数据库服务器将释放任何引用计数为零的智能大对象。引用数表示引用智能大对象的数据库列数。
-
返回标识智能大对象的文件描述符。
数据库服务器使用调用 ifx_lo_create() 建立的缺省参数来确定是否锁定或记录智能大对象上后续的操作。
ifx_lo_def_create_spec() 函数
ifx_lo_def_create_spec() 函数创建智能大对象规范结构。
语法
ifx_lo_def_create_spec(lospec)
参数
该函数接受以下参数：
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | I/O | 智能大对象规范结构 |
用法
ifx_lo_def_create_spec() 函数创建智能大对象结构并初始化字段为空。如果不更改这些值，则空值告知数据库服务器使用系统指定的缺省值来存储智能大对象的存储特征。
ifx_lo_open() 函数
ifx_lo_open() 函数打开智能大对象。
语法
ifx_lo_open(lofd, loptr, flags)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输出 | 智能大对象文件描述符。该文件描述符只在当前数据库连接中有效。 |
| loptr | SQL_INFX_UDT_FIXED | 输入 | 智能大对象指针结构 |
| flags | SQL_INTEGER | 输入 | 打开智能大对象的模式。 |
用法
ifx_lo_open() 函数执行以下步骤来打开智能大对象：
- 以 flags 指定的访问模式打开 loptr 智能大对象。
- 将查找位置设置为字节零。
- 锁定智能大对象。
数据库服务器不会检查智能大对象的访问权限。您的应用程序必须确保用户或应用程序可信。
如下表所述，访问模式确定锁的类型。
| 访问模式 | 锁的类型 |
|---|---|
| 脏读 | 没有锁 |
| 只读 | 共享锁 |
| 只写， 写/附加，或读/写 | 更新锁。当对智能大对象调用 ifx_lo_write() 或 ifx_lo_writewithseek() 时，数据库服务器会将锁升级为互斥锁。 |
当当前连接终止时，数据库服务器失去此锁。数据库服务器在下一次调用需要锁的函数时再次获取该锁。
另外，可以使用 BEGIN WORK 事务块，将 COMMIT WORK 或 ROLLBACK WORK 语句放到需要使用锁的最后一条语句之后。
-
分配具有当前连接的智能大对象。
当关闭连接时，数据库服务器将释放任何引用计数零的智能大对象。引用数表示引用智能大对象的数据库列数。
-
返回标识智能大对象的文件描述符。
数据库服务器使用调用 ifx_lo_open() 建立的缺省参数来确定是否锁定或记录智能大对象上后续的操作。
ifx_lo_read() 函数
ifx_lo_read() 函数从打开的智能大对象读取数据。
语法
ifx_lo_read(lofd, buf)
参数
该函数接受以下参数。
| 函数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| buf | SQL_CHAR | 输出 | 指向函数将读取数据的字符缓冲区的指针 |
用法
ifx_lo_read() 函数从打开的智能大对象读取数据。该读取从 lofd 当前的查找位置开始。可以调用 ifx_lo_tell() 获取当前查找位置。
ifx_lo_read() 函数读取 cbValueMax 字节数据。cbValueMax 是 SQLBindParameter() 和 SQLBindCol() 的输入参数。buf 或 cbValueMax 的大小不能超过 2 千兆字节。要读取大于 2 千兆字节的智能大对象，请在 2 千兆字节的 chunk 中读取它。ifx_lo_read() 函数将这些数据读入 buf 指向的用户定义缓冲区。
如果 SQLBindParameter() 或 SQLBindCol() 返回 SQL_SUCCESS，则 pcbValue（这些函数的参数）包含函数从智能大对象中读取的字节数。如果 SQLBindParameter() 或 SQLBindCol() 返回 SQL_SUCCESS_WITH_INFO，则 pcbValue 包含从智能大对象中读取的字节数。
ifx_lo_readwithseek() 函数
ifx_lo_readwithseek() 函数执行查找操作，然后从打开的智能大对象中读取数据。
语法
ifxlo_readwithseek(_lofd, buf, offset, whence)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| buf | SQL_CHAR | 输出 | 指向函数将读取数据的字符缓冲区的指针 |
| offset | SQL_BIGINT | 输入 | 从起始查找位置偏移的偏移量，以字节为单位。使用 SQL_C_LONG 或 SQL_C_SHORT，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 offset。 |
| whence | SQL_INTEGER | 输入 | 开始查找位置。可能值为： LO_SEEK_CUR 当前查找位置在智能大对象中的位置 LO_SEEK_END 智能大对象的末尾位置 LO_SEEK_SET 智能大对象的起始位置 |
用法
ifx_lo_readwithseek() 函数执行查找操作并读取来自智能大对象的数据。该读取从 offset 和 whence 参数指定的查找位置开始。
ifx_lo_readwithseek() 函数读取数据的 cbValueMax 字节。cbValueMax 是 SQLBindParameter() 和 SQLBindCol() 的输入参数。buf 或 cbValueMax 的大小不能超过 2 GB。要读取大于 2 千兆字节的智能大对象，请在 2-GB chunk 中读取。ifx_lo_readwithseek() 函数将数据读到 buf 指向的用户定义的缓冲区。
如果 SQLBindParameter() 或 SQLBindCol() 返回 SQL_SUCCESS，则 pcbValue（这些函数的一个参数）包含函数从智能大对象中读取的字节数。如果 SQLBindParameter() 或 SQLBindCol() 返回 SQL_SUCCESS_WITH_INFO，则 pcbValue 包含可用于从智能大对象读取的字节数。
ifx_lo_seek() 函数
ifx_lo_seek() 函数设置打开的智能大对象上下一次读取或写入操作的文件位置。
语法
ifxlo_seek(_lofd, offset, whence, seek_pos)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| offset | SQL_BIGINT | 输入 | 从起始查找位置偏移的偏移量，以字节为单位。使用 SQL_C_LONG 或 SQL_C_SHORT，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 offset。 |
| whence | SQL_INTEGER | 输入 | 开始查找位置。可能值为： LO_SEEK_CUR 当前查找位置在智能大对象中的位置 LO_SEEK_END 智能大对象的末尾位置 LO_SEEK_SET 智能大对象的起始位置 |
| seek_pos | SQL_BIGINT | I/O | 新的查找位置。使用 SQL_C_LONG，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 eek_pos。 |
用法
ifx_lo_seek() 函数将 lofd 的查找位置设置为 offset 和 whence 参数指示的查找位置。
ifx_lo_specget_estbytes() 函数
ifx_lo_specget_estbytes() 函数从智能大对象规范结构中获取估计的字节数。
语法
ifx_lo_specget_estbytes(lospec, estbytes)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| estbytes | SQL_BIGINT | 输出 | 智能大对象的估计最终大小，以字节为单位。此估计值是智能大对象优化程序的优化提示。使用 SQL_C_LONG，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 estbytes。 |
用法
ifx_lo_specget_estbytes() 函数获取智能大对象规范结构的估计的字节数。
ifx_lo_specget_extsz() 函数
fx_lo_specget_extsz() 函数从智能大对象规范结构获取分配的 extent。
语法
ifx_lo_specget_extsz(lospec, extsz)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| extsz | SQL_INTEGER | 输出 | 智能大对象的 Extent 大小，以字节为单位。该值是当数据库服务器写入超出当前范围的末尾时，为智能大对象分配的分配 Extent 的大小。该值会覆盖数据库服务器估计的 extent 大小。 |
用法
ifx_lo_specget_extsz() 函数从智能大对象规范结构获取分配的 extent。
ifx_lo_specget_flags() 函数
ifx_lo_specget_flags() 函数从智能大对象获取创建时间标记。
语法
ifx_lo_specget_flags(lospec, flags)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| flags | SQL_INTEGER | 输出 | 创建时间标记。 |
ifx_lo_specget_maxbytes() 函数
ifx_lo_specget_maxbytes() 函数获取智能大对象规范结构的最大字节数。
语法
ifx_lo_specget_maxbytes(lospec, maxbytes)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| maxbytes | SQL_BIGINT | 输入 | 智能大对象的最大大小，以字节为单位。使用 SQL_C_LONG 而是不是使用 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 maxbytes。 |
用法
ifx_lo_specget_maxbytes() 函数获取智能大对象规范结构的最大字节数。
ifx_lo_specget_sbspace() 函数
ifx_lo_specget_sbspace() 函数从智能大对象规范结构获取 sbspace 的名称。
语法
ifx_lo_specget_sbspace(lospec, sbspace)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| sbspace | SQL_CHAR | 输出 | 智能大对象的 sbspace 名称。sbspace 名称可以达到 18 字节长并且必须是以空字符串为终止。 |
用法
ifx_lo_specget_sbspace() 函数返回存储智能大对象的 sbspace 名称。该函数将 (pcbValue-1) 字节复制到 sbspace 缓冲区并确保它以空字符串终止。pcbValue 是 SQLBindParameter() 和 SQLBindCol() 的参数。
ifx_lo_specset_estbytes() 函数
ifx_lo_specset_estbytes() 函数设置智能大对象规范结构中估计的字节数。
语法
ifx_lo_specset_estbytes(lospec, estbytes)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| estbytes | SQL_BIGINT | 输入 | 智能大对象的估计最终值，以字节为单位。此估计值是智能大对象优化程序的优化提示。该值不能超过 2 千兆字节。 如果在创建新的智能大对象时，未指定 estbytes 值，则数据库服务器从存储特征的继承层次结构中获取该值。 除非您指定智能大对象的估计大小，否则不要更改此系统值。如果您设置了智能大对象的估计大小，则不要指定的值不要高出智能大对象的最终大小太多。否则，数据库服务器可能分配未使用的存储。 使用 SQL_C_LONG 或 SQL_C_SHORT，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 estbytes。 |
用法
ifx_lo_specset_estbytes() 函数设置智能大对象规范结构中估计的字节数。
ifx_lo_specset_extsz() 函数
ifx_lo_specset_extsz() 函数设置智能大对象规范结构中的分配 Extent 大小。
语法
ifx_lo_specset_extsz(lospec, extsz)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| extsz | SQL_INTEGER | 输入 | 智能大对象的 Extent 大小，以字节为单位。该值是当数据库服务器写入超出当前范围的末尾时，为智能大对象分配的分配 Extent 的大小。该值会覆盖数据库服务器估计的 extent 大小。 如果在创建新的智能大对象时，未指定 extsz 值，则数据库服务器尝试根据智能大对象的历史操作和从存储特征获取的继承层次结构的其它存储特征（例如，最大字节数）来优化 extent 大小。 除非您知道智能大对象的分配的 extent 大小，否则请不要更改此系统值。只有遇到苛刻存储分片的应用程序才能设置分配 extent 大小。有关这些应用程序，请确保您确切知道 extent 智能大对象的字节数。 |
用法
ifx_lo_specset_extsz() 函数设置智能大对象规范结构中的分配 Extent 大小。
ifx_lo_specset_flags() 函数
ifx_lo_specset_flags() 函数设置智能大对象规范结构中的创建时间标志。
语法
ifx_lo_specset_flags(lospec, flags)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构 |
| flags | SQL_INTEGER | 输入 | 创建时间标志 |
用法
ifx_lo_specset_flags() 设置智能大对象规范结构中的创建时间标志。
ifx_lo_specset_maxbytes() 函数
ifx_lo_specset_maxbytes() 函数设置智能大对象规范结构中的最大字节数。
语法
ifx_lo_specset_maxbytes(lospec, maxbytes)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构。 |
| maxbytes | SQL_BIGINT | 输入 | 智能大对象的最大大小，以字节为单位。该值不能超过 2 千兆字节。使用 SQL_C_LONG 或 SQL_C_SHORT 而是不是使用 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 maxbytes。 |
用法
ifx_lo_specset_maxbytes() 函数设置智能大对象规范结构中的最大字节数。
ifx_lo_specset_sbspace() 函数
ifx_lo_specset_sbspace() 函数设置智能大对象规范结构中的 sbspace 名称。
语法
ifx_lo_specset_sbspace(lospec, sbspace)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lospec | SQL_INFX_UDT_FIXED | 输入 | 智能大对象规范结构。 |
| sbspace | SQL_CHAR | 输入 | 智能大对象的 sbspace 名称。sbspace 名称可以达到 18 字节长并且必须是以空字符串为终止。如果在创建智能大对象时，未指定 sbspace，则数据库服务器从列信息或从 onconfig 文件的 SBSPACENAME 参数获取 sbspace 名称。 |
用法
ifx_lo_specset_sbspace() 函数使用 pcbValue 确定 sbspace 名称的长度。pcbValue 是 SQLBindParameter() 和 SQLBindCol() 的一个参数。
ifx_lo_stat() 函数
ifx_lo_stat() 函数初始化智能大对象状态结构。
语法
ifx_lo_stat(lofd, lostat)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| lostat | SQL_INFX_UDT_FIXED | I/O | 智能大对象状态结构 |
用法
在调用 ifx_lo_stat() 之前，请调用 SQLGetInfo() 获取智能大对象状态结构的大小。使用该大小为结构分配内存。
ifx_lo_stat() 函数分配智能大对象状态结构并使用智能大对象的状态信息初始化它。
ifx_lo_stat_atime() 函数
ifx_lo_stat_atime() 函数检索智能大对象的最近一次访问时间。
语法
ifx_lo_stat_atime(lostat, atime)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lostat | SQL_INFX_UDT_FIXED | 输入 | 智能大对象状态结构 |
| atime | SQL_INTEGER | 输出 | 智能大对象最近一次访问的时间，以秒为单位。数据库服务器仅当为智能大对象设置 LO_KEEP_LASTACCESS _TIME 标志时，才会维护最近访问时间。 |
用法
ifx_lo_stat_atime() 函数检索智能大对象的最近一次访问时间。
ifx_lo_stat_cspec() 函数
ifx_lo_stat_cspec() 函数检索智能大对象结构。
语法
ifx_lo_stat_cspec(lostat, lospec)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lostat | SQL_INFX_UDT_FIXED | 输入 | 智能大对象状态结构 |
| lospec | SQL_INFX_UDT_FIXED | 输出 | 智能大对象规范结构 |
用法
ifx_lo_stat_cspec() 函数检索智能大对象规范结构，并返回指向结构的指针。
ifx_lo_stat_ctime() 函数
ifx_lo_stat_ctime() 函数检索智能大对象最近一次更改的时间。
语法
ifx_lo_stat_ctime(lostat, ctime)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lostat | SQL_INFX_UDT_FIXED | 输入 | 智能大对象状态结构 |
| ctime | SQL_INTEGER | 输出 | 智能大对象最近一次更改的时间，以秒为单位。最近一次更改时间包括存储特征的修改，引用次数的更改和写入智能大对象。 |
用法
ifx_lo_stat_ctime() 函数检索智能大对象最近一次更改的时间。
ifx_lo_stat_refcnt() 函数
ifx_lo_stat_refcnt() 函数检索智能大对象的引用次数。
语法
ifx_lo_stat_refcnt(lostat, refcount)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lostat | SQL_INFX_UDT_FIXED | 输入 | 智能大对象状态结构 |
| refcount | SQL_INTEGER | 输出 | 智能大对象的引用次数。该值是数据库列引用智能大对象的次数。 |
用法
ifx_lo_stat_refcnt() 函数检索智能大对象的引用次数。
数据库服务器可以在智能大对象引用次数为零时，或发生以下之一的情况时，移除智能大对象，重新利用分配给它的资源：
- 提交引用计数递减为零的事务。
- 创建智能大对象的连接终止，但引用计数不增加。
将智能大对象指针结构存储在一行中时，数据库服务器将增加一个引用计数。
ifx_lo_stat_size() 函数
ifx_lo_stat_size() 函数检索智能大对象的大小，
语法
ifx_lo_stat_size(lostat, size)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lostat | SQL_INFX_UDT_FIXED | 输入 | 智能大对象状态结构 |
| size | SQL_BIGINT | 输出 | 智能大对象的大小，以字节为单位。该值不能超过 2 千兆字节。使用 SQL_C_LONG 而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 size。 |
用法
ifx_lo_stat_size() 函数检索智能大对象的大小。
ifx_lo_tell() 函数
ifx_lo_tell() 函数检索打开的智能大对象的当前文件或查找位置。
语法
ifx_lo_tell(lofd, seek_pos)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| seek_pos | SQL_BIGINT | I/O | 新的查找位置，智能大对象上的下一次读或写操作的偏移量。使用 SQL_C_LONG 而不是使用缺省的GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 seek_pos。 |
用法
ifx_lo_tell() 函数检索打开的智能大对象的当前文件或查找位置。
该函数当智能大对象长达 2 千兆字节时也能正常运行。
ifx_lo_truncate() 函数
ifx_lo_truncate() 函数在指定位置截断智能大对象。
语法
ifx_lo_truncate(lofd, offset)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| offset | SQL_BIGINT | 输入 | 智能大对象的末尾。如果该值超出智能大对象的末尾，则函数扩展智能大对象。如果该值小于智能大对象的末尾，则数据库服务器将回收从偏移位置到智能大对象的末尾的所有存储。 使用 SQL_C_LONG 或 SQL_C_SHORT，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 offset。 |
用法
ifx_lo_truncate() 函数设置将智能大对象的末尾设置为 offset 参数指定的位置。
ifx_lo_write() 函数
ifx_lo_write() 函数将数据写入智能大对象。
语法
ifx_lo_write(lofd, buf)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| buf | SQL_CHAR | 输入 | 包含函数写入到智能大对象中的数据的缓冲区。该缓冲区的大小不能超过 2 千兆字节。 |
用法
ifx_lo_write() 函数将数据写入智能大对象。写入从 lofd 的当前查找位置开始。可以调用 ifx_lo_tell() 获取当前查找位置。
ifx_lo_write() 函数写入 cbValueMax 字节数据。cbValueMax 是 SQLBindParameter() 和 SQLBindCol() 的输入参数。buf 或 cbValueMax 的大小不能超过 2 GB。要写入一个大于 2 千兆字节的智能大对象，将其写入 2-GB chunk。ifx_lo_write() 函数获取从用户定义的缓冲区到 buf 指向的数据。
如果 SQLExecDirect() 或 SQLExecute() 返回 SQL_SUCCESS_WITH_INFO，则数据库服务器将写入少于 cbValueMax 字节的数据到智能大对象，pcbValue （这些函数的一个参数）包含函数写入的字节数。当 sbspace 超出空间范围时，会发生此情况。
ifx_lo_writewithseek() 函数
ifx_lo_writewithseek() 函数执行查找操作然后将数据写入到打开的智能大对象。
语法
ifx_lo_writewithseek(lofd, buf, offset, whence)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| lofd | SQL_INTEGER | 输入 | 智能大对象文件描述符 |
| buf | SQL_CHAR | 输入 | 包含函数写入到智能大对象中的数据的缓冲区。该缓冲区的大小不能超过 2 千兆字节。 |
| offset | SQL_BIGINT | 输入 | 起始查找位置的偏移量，以字节为单位。使用 SQL_C_LONG 或 SQL_C_SHORT，而不是使用缺省的 GBase 8s ODBC Driver C 数据类型 SQL_C_CHAR 作为 offset。 |
| whence | SQL_INTEGER | 输入 | 开始查找位置。可能值为： LO_SEEK_CUR 当前查找位置在智能大对象中的位置 LO_SEEK_END 智能大对象的末尾位置 LO_SEEK_SET 智能大对象的起始位置 |
用法
ifx_lo_writewithseek() 函数执行查找操作并将数据写入到自智能大对象。该写入从 offset 和 whence 参数指定的 lofd 查找位置开始。
ifx_lo_writewithseek() 函数写入 cbValueMax 字节数据。cbValueMax 是 SQLBindParameter() 和 SQLBindCol() 的一个输入参数。buf 或 cbValueMax 的大小不能超过 2 GB。要写入大于 2 GB 的智能大对象，将它写入到 2-GB chunk。ifx_lo_writewithseek() 函数从 buf 指向的用户定义的缓冲区获取数据。
如果 SQLExecDirect() 或 SQLExecute() 返回 SQL_SUCCESS_WITH_INFO，则数据库服务器写入少于 cbValueMax 字节的数据到智能大对象，pcbValue（这些函数的一个参数）包含函数写入的字节数。当 sbspace 超出空间范围时，发生此情况。
行和集合的函数
本节描述 GBase 8s ODBC Driver 提供用于行和集合的客户端函数。
ifx_rc_count() 函数
ifx_rc_count() 函数返回行或集合中元素的数量。
语法
ifx_rc_count(rowcount, rchandle)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rowcount | SQL_SMALLINT | 输出 | 行或集合中元素的数量 |
| rchandle | HINFX_RC | 输入 | 行或集合存取的句柄 |
用法
ifx_rc_count() 函数返回行或集合中元素的数量。
ifx_rc_create() 函数
ifx_rc_create() 函数为行或集合创建缓冲区。
语法
ifx_rc_create(rchandle, typespec)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rchandle | HINFX_RC | 输出 | 行或集合缓冲区的句柄 |
| typespec | SQL_CHAR | 输入 | 缓冲区的类型规范。参见下表。 |
下表描述了 typespec 参数的语法。
| 缓冲区的类型 | 语法 | 示例 |
|---|---|---|
| 不固定型集合 | COLLECTION | COLLECTION |
| 固定型集合 | COLLECTION {SET | MULTISET | LIST} (type not null) 或 {SET | MULTISET | LIST (type not null) type 是集合中元素的 GBase 8s SQL 数据类型 | COLLECTION SET (int not null) 或 SET (int not null) |
| 不固定型集合 | ROW | ROW |
| 固定型集合 | ROW [“name”] (field_id type [, field_id type, ...]) 其中： 1. name 是整个行的可选名称 2. field_id 是字段的名称 3. type 是字段的 GBase 8s SQL 数据类型 | ROW “employee_t” (name char(255), id_num int, dept int) |
用法
ifx_rc_create() 函数为行和集合分片内存，并返回一个句柄到缓冲区。下表描述了函数初始化缓冲区的方式。
| 缓冲区的类型 | 行或集合的初始值 | 行或集合的内容的初始值 |
|---|---|---|
| Fixed-type collection | 非空 | 空 |
| Fixed-type row | 非空 | 每个值都为空 |
| Unfixed-type collection | 空 | 空 |
| Unfixed-type row | 空 | 空 |
对于行，函数将第一个元素设置为查找位置。空集合缓冲区不具有查找位置。
ifx_rc_delete() 函数
ifx_rc_delete() 函数从集合删除元素。
语法
ifx_rc_delete(rchandle, action, jump)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rchandle | HINFX_RC | 输入 | 集合缓冲区的句柄 |
| action | SQL_SMALLINT | 输入 | 元素相对于查找位置的位置。值可能为： ● SQL_INFX_RC_ABSOLUTE：: 元素 jump ，缓冲区中的第一个元素是元素 1 ● SQL_INFX_RC_CURRENT：当前元素 ● SQL_INFX_RC_FIRST：第一个元素 ● SQL_INFX_RC_LAST：最后一个元素 ● SQL_INFX_RC_NEXT：下一个元素 ● SQL_INFX_RC_PRIOR：上一个元素 ● SQL_INFX_RC_RELATIVE：: jump 跳过当前元素的元素 |
| jump | SQL_SMALLINT | 输入 | 当 action 是 SQL_INFX_RC_ABSOLUTE 或 SQL_INFX_RC_RELATIVE 的偏移量 |
用法
ifx_rc_delete() 函数从 action 和 jump 指定的位置删除集合中的元素。该函数将查找位置设置为被删除的值的位置。从行中删除元素是不可能的。
ifx_rc_describe() 函数
ifx_rc_describe() 函数返回有关行或集合数据类型的信息或行或集合中元素的信息。
语法
ifx_rc_describe(rchandle, fieldnum, fieldname, typecode,columnsize, decdigits, nullable, typename, typeowner)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rchandle | HINFX_RC | 输入 | 行或集合缓冲区的句柄 |
| fieldnum | SQL_SMALLINT | 输入 | 字段数。如果该值为 0，则函数返回整个行或集合的信息。对于集合，任何不是 0 的值会使函数返回集合中元素的信息。对于行，该值指定函数返回信息的元素。 |
| fieldname | SQL_CHAR | 输出 | 字段名称。该函数仅当元素在行中时返回此值。 |
| typecode | SQL_SMALLINT | 输出 | 元素的 GBase 8s ODBC Driver SQL 数据类型 |
| columnsize | SQL_INTEGER | 输出 | 列大小。对于字符元素，该值是列的大小，以字节为单位。对于数字元素，该值是精度。对于其它数据类型，该函数不会返回值。 |
| decdigits | SQL_SMALLINT | 输出 | 小数点位数。对于数字元素，该值是小数点后小数位数。杜宇其它数据类型，该函数不会返回值。 |
| nullable | SQL_SMALLINT | 输出 | NULL 指示符。值可能为： SQL_NO_NULLS SQL_NULLABLE |
| typename | SQL_CHAR | 输出 | 类型名称。对于已命名的行，该值是行的名称。对于集合和未命名行，此函数不会返回值。 |
| typeowner | SQL_CHAR | 输出 | 类型所有者。该值是数据类型的所有者的名称。该名称的长度不能超出 18 个字符。 |
用法
ifx_rc_describe() 函数返回有关行或集合数据类型的信息或行或集合中元素的信息。对于集合中的元素，该信息与集合中所有元素的信息一致。该函数不会更改查找位置。
ifx_rc_fetch() 函数
ifx_rc_fetch() 函数检索行或集合中元素的值。
语法
ifx_rc_fetch(result, rchandle, action, jump)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| result | 元素的数据类型 | 输出 | 检索到的值 |
| rchandle | HINFX_RC | 输入 | 行或集合缓冲区的句柄 |
| action | SQL_SMALLINT | 输入 | 元素相对于查找位置的位置。值可能为： ● SQL_INFX_RC_ABSOLUTE：: 元素 jump ，缓冲区中的第一个元素是元素 1 ● SQL_INFX_RC_CURRENT：当前元素 ● SQL_INFX_RC_FIRST：第一个元素 ● SQL_INFX_RC_LAST：最后一个元素 ● SQL_INFX_RC_NEXT：下一个元素 ● SQL_INFX_RC_PRIOR：上一个元素 ● SQL_INFX_RC_RELATIVE：: jump 跳过当前元素的元素 |
| jump | SQL_SMALLINT | 输入 | 当 action 是 SQL_INFX_RC_ABSOLUTE 或 SQL_INFX_RC_RELATIVE 时，偏移 |
用法
ifx_rc_fetch() 函数检索由 action 和 jump 指定的元素的值，并在 result 中返回值。该函数将查找位置设置为刚获取的值的位置。
ifx_rc_free() 函数
ifx_rc_free() 函数释放行或集合句柄。
语法
ifx_rc_free(rchandle)
参数
该函数接受以下参数，
| 参数 | 类型 | 用于 | 模式 |
|---|---|---|---|
| rchandle | HINFX_RC | 输入 | 行或集合缓冲区的句柄 |
用法
ifx_rc_free() 函数释放与集合或行句柄相关联的资源，并释放此句柄。
ifx_rc_insert() 函数
ifx_rc_insert() 函数将新的值插入到集合中。
语法
ifx_rc_insert(rchandle, value, action, jump)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rchandle | HINFX_RC | 输入 | 集合缓冲区的句柄 |
| value | 元素的数据类型 | 输入 | 要插入的值 |
| action | SQL_SMALLINT | 输入 | 元素相对于查找位置的位置。值可能为： ● SQL_INFX_RC_ABSOLUTE：: 元素 jump ，缓冲区中的第一个元素是元素 1 ● SQL_INFX_RC_CURRENT：当前元素 ● SQL_INFX_RC_FIRST：第一个元素 ● SQL_INFX_RC_LAST：最后一个元素 ● SQL_INFX_RC_NEXT：下一个元素 ● SQL_INFX_RC_PRIOR：上一个元素 ● SQL_INFX_RC_RELATIVE：: jump 跳过当前元素的元素 |
| jump | SQL_SMALLINT | 输入 | 当 action 是 SQL_INFX_RC_ABSOLUTE 或 SQL_INFX_RC_RELATIVE 时，偏移 |
用法
ifx_rc_insert() 函数将新的元素插入到 action 和 jump 指定之前的位置。函数将查找位置设置为已插入的值的位置。无法向行插入新的元素。
下表描述了每种集合类型的允许的插入操作。
| 集合的类型 | 允许插入的位置 |
|---|---|
| List | 缓冲区中的任何位置 |
| Set 或 multiset | 缓冲区的末尾 |
如果由 action 和 jump 值的查找位置超出缓冲区的末尾，则 ifx_rc_insert() 将新的元素附加到缓冲区的末尾。同样地，如果 action 和 jump 指定查找位置在缓冲区的起始位置之前，则 ifx_rc_insert() 在缓冲区的开头插入新的元素。如果 action 指定一个插入的指针而不是 set 或 multiset 的末尾，则 ifx_rc_insert() 失败。
例如，如果 action 是 SQL_INFX_RC_LAST，则该函数在最后一个元素之前插入新值。要附加新的元素，请采取以下操作：
- 将查找位置设置为缓冲区的末尾，并将 action 设置为 SQL_INFX_RC_NEXT。
- 将 action 设置为 SQLINFX_RC_ABSOLUTE 或 SQL_INFX_RC_RELATIVE ，并将 _jump 设置为超出缓冲区末尾的值。
要在缓冲区的开始位置插入新的值，请将 action 设置为 SQL_INFX_RC_FIRST。
ifx_rc_isnull() 函数
ifx_rc_isnull() 函数返回指示行或集合是否为空的值。
语法
ifx_rc_isnull(nullflag, rchandle)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| nullflag | SQL_SMALLINT | 输出 | 指示行或集合是否为空的标志。值可能为： ● TRUE ● FALSE |
| rchandle | HINFX_RC | 输入 | 行或集合的句柄 |
用法
ifx_rc_isnull() 函数返回指示行或集合是否为空的值。
ifx_rc_setnull() 函数
ifx_rc_setnull() 函数将行或集合设置为空。
语法
ifx_rc_setnull(rchandle)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rchandle | HINFX_RC | 输入 | 行或集合缓冲区的句柄 |
用法
ifx_rc_setnull() 函数将行或集合设置为空。ifx_rc_setnull() 函数不会将行或集合中的每个元素设置为空。
ifx_rc_typespec() 函数
ifx_rc_typespec() 函数返回行或集合的类型规范。
语法
ifx_rc_typespec(typespec, rchandle, flag)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| typespec | SQL_CHAR | 输出 | 类型规范。该值的格式与 ifx_rc_create() 的规范语法相同。 |
| rchandle | HINFX_RC | 输入 | 行或集合缓冲区的句柄 |
| flag | SQL_SMALLINT | 输入 | 指定是返回当前还是原始类型规范的标志。如果该值为 TRUE，则函数返回原始类型规范。否则，该函数返回当前类型规范。 |
用法
ifx_rc_typespec() 函数返回行或集合的类型规范。
ifx_rc_update() 函数
ifx_rc_update() 函数更新行或集合中的元素的值。
语法
ifx_rc_update(rchandle, value, action, jump)
参数
该函数接受以下参数。
| 参数 | 类型 | 用于 | 描述 |
|---|---|---|---|
| rchandle | HINFX_RC | 输入 | 行或集合缓冲区的句柄 |
| value | 元素的数据类型 | 输入 | 更新的元素的值 |
| action | SQL_SMALLINT | 输入 | 元素相对于查找位置的位置。值可能为： ● SQL_INFX_RC_ABSOLUTE：: 元素 jump ，缓冲区中的第一个元素是元素 1 ● SQL_INFX_RC_CURRENT：当前元素 ● SQL_INFX_RC_FIRST：第一个元素 ● SQL_INFX_RC_LAST：最后一个元素 ● SQL_INFX_RC_NEXT：下一个元素 ● SQL_INFX_RC_PRIOR：上一个元素 ● SQL_INFX_RC_RELATIVE：: jump 跳过当前元素的元素 |
| jump | SQL_SMALLINT | 输入 | 当 action 是 SQL_INFX_RC_ABSOLUTE 或 SQL_INFX_RC_RELATIVE 时，偏移 |
用法
ifx_rc_update() 函数更改 action 和 jump 指定的位置之前的元素的值。该函数将查找位置设置为已更改的值的位置。